/*
 * Copyright 2002-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.context.annotation;

import java.lang.annotation.Annotation;

import org.springframework.core.GenericTypeResolver;
import org.springframework.core.annotation.AnnotationAttributes;
import org.springframework.core.type.AnnotationMetadata;
import org.springframework.lang.Nullable;
import org.springframework.util.Assert;

/**
 *
 * 用于选择导入的{@link ImportSelector}实现的方便基类基于注解中的{@link AdviceMode}值(例如{@code @Enable*}
 * (注解)。
 *
 * @author Chris Beams
 * @since 3.1
 * @param <A> annotation containing {@linkplain #getAdviceModeAttributeName() AdviceMode attribute}
 */
public abstract class AdviceModeImportSelector<A extends Annotation> implements ImportSelector {

	/**
	 * 默认advice模式属性名。
	 */
	public static final String DEFAULT_ADVICE_MODE_ATTRIBUTE_NAME = "mode";


	/**
	 *
	 * 通用类型{@code A}所指定的注释的{@link AdviceMode}属性的名称。
	 * 默认是{@value #DEFAULT_ADVICE_MODE_ATTRIBUTE_NAME}。但子类可以覆盖以进行定制。
	 *
	 */
	protected String getAdviceModeAttributeName() {
		return DEFAULT_ADVICE_MODE_ATTRIBUTE_NAME;
	}

	/**
	 * 这个实现从通用元数据中解析注解的类型，并验证（a）该注解实际上存在于导入的{@code @Configuration}类上，
	 * 以及（b）给定的注解有一个{@linkplain #getAdviceModeAttributeName() advice mode attribute}的类型{@link AdviceMode}。
	 *
	 * 然后，{@link #selectImports(AdviceMode)}方法被调用，允许具体实现以安全和方便的方式选择进口。
	 * 如果预期的注解{@code A}在导入的{@code @Configuration}类上不存在
	 * ，或者如果{@link #selectImports(AdviceMode)}返回{@code null}，则抛出IllegalArgumentException。
	 */
	@Override
	public final String[] selectImports(AnnotationMetadata importingClassMetadata) {
		//获取AdviceModeImportSelector的泛型
		Class<?> annType = GenericTypeResolver.resolveTypeArgument(getClass(), AdviceModeImportSelector.class);
		Assert.state(annType != null, "Unresolvable type argument for AdviceModeImportSelector");
		//获取注解的参数
		AnnotationAttributes attributes = AnnotationConfigUtils.attributesFor(importingClassMetadata, annType);
		if (attributes == null) {
			throw new IllegalArgumentException(String.format(
					"@%s is not present on importing class '%s' as expected",
					annType.getSimpleName(), importingClassMetadata.getClassName()));
		}
		//获取注解 mode属性
		AdviceMode adviceMode = attributes.getEnum(getAdviceModeAttributeName());
		String[] imports = selectImports(adviceMode);
		if (imports == null) {
			throw new IllegalArgumentException("Unknown AdviceMode: " + adviceMode);
		}
		return imports;
	}

	/**
	 * 根据给定的{@code AdviceMode}来决定哪些类应该被导入。
	 * 从这个方法中返回{@code null}表明{@code AdviceMode}无法被处理或未知，应该抛出一个{@code IllegalArgumentException}。
	 * @param adviceMode the value of the {@linkplain #getAdviceModeAttributeName()
	 * advice mode attribute} for the annotation specified via generics.
	 * @return array containing classes to import (empty array if none;
	 * {@code null} if the given {@code AdviceMode} is unknown)
	 */
	@Nullable
	protected abstract String[] selectImports(AdviceMode adviceMode);

}
